Safe, Fast, and user-friendly wrapper around the CUDA Driver API.

Low level CUDA interop

Because additions to CUDA and libraries that use CUDA are everchanging, this library provides unsafe functions for retrieving and setting handles to raw cuda_sys objects. This allows advanced users to embed libraries that rely on CUDA, such as OptiX. We also re-export cuda_sys as a [sys] module for convenience.

CUDA Terminology:

Devices and Hosts:

This crate and its documentation uses the terms "device" and "host" frequently, so it's worth explaining them in more detail. A device refers to a CUDA-capable GPU or similar device and its associated external memory space. The host is the CPU and its associated memory space. Data must be transferred from host memory to device memory before the device can use it for computations, and the results must then be transferred back to host memory.

Contexts, Modules, Streams and Functions:

A CUDA context is akin to a process on the host - it contains all of the state for working with a device, all memory allocations, etc. Each context is associated with a single device.

A Module is similar to a shared-object library - it is a piece of compiled code which exports functions and global values. Functions can be loaded from modules and launched on a device as one might load a function from a shared-object file and call it. Functions are also known as kernels and the two terms will be used interchangeably.

A Stream is akin to a thread - asynchronous work such as kernel execution can be queued into a stream. Work within a single stream will execute sequentially in the order that it was submitted, and may interleave with work from other streams.

Grids, Blocks and Threads:

CUDA devices typically execute kernel functions on many threads in parallel. These threads can be grouped into thread blocks, which share an area of fast hardware memory known as shared memory. Thread blocks can be one-, two-, or three-dimensional, which is helpful when working with multi-dimensional data such as images. Thread blocks are then grouped into grids, which can also be one-, two-, or three-dimensional.

CUDA devices often contain multiple separate processors. Each processor is capable of excuting many threads simultaneously, but they must be from the same thread block. Thus, it is important to ensure that the grid size is large enough to provide work for all processors. On the other hand, if the thread blocks are too small each processor will be under-utilized and the code will be unable to make effective use of shared memory.

Usage:

Before using cust, you must install the CUDA development libraries for your system. Version 9.0 or newer is required. You must also have a CUDA-capable GPU installed with the appropriate drivers.